home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2001 May / SGI Freeware 2001 May - Disc 3.iso / relnotes / vnc.txt < prev    next >
Text File  |  2001-04-12  |  11KB  |  334 lines
  1.  
  2. Xt-based VNC viewer version 3.3.3r1
  3. ===================================
  4.  
  5. VNC is Copyright (C) 1999 AT&T Laboratories Cambridge.  All Rights Reserved.
  6. This software is distributed under the GNU General Public Licence as published
  7. by the Free Software Foundation.
  8.  
  9.  
  10. Features
  11. --------
  12.  
  13. * Xt-based, so it's a better behaved X application (sets window class, etc).
  14.  
  15. * Can be customised through X resources instead of awkward command-line options
  16.   (of course there are still command-line options for common cases).
  17.  
  18. * Specifying the VNC server to connect to can be done either on the
  19.   command-line as before, or with a dialog window.  Either the host name or
  20.   display number can be omitted.  So for example ":1" means display number 1 on
  21.   the same machine, and "snoopy" means "snoopy:0" i.e. display 0 on machine
  22.   "snoopy".
  23.  
  24. * The password can be entered in a dialog window, or taken from the tty, or a
  25.   password file.
  26.  
  27. * A full-screen mode with "bump scrolling" is supported.  This doesn't work
  28.   completely with all window managers, since it breaks all the rules of the
  29.   ICCCM.  It tends to work better when the viewer is started in full-screen
  30.   mode than when switching to it from normal mode.
  31.  
  32. * Supports the PRIMARY selection as well as the cut buffer.  The selection is
  33.   normally transferred to and from the VNC server when the mouse enters or
  34.   leaves the viewer window.  This behaviour is customisable through resources.
  35.   Note that at the time of writing Xvnc still only supports the cut buffer.
  36.  
  37. * Has a popup window containing a set of buttons which perform various actions.
  38.   It is usually brought up by pressing F8, but this is customisable, as is the
  39.   entire contents of the popup.  Actions which buttons in the popup window can
  40.   perform include:
  41.  
  42.    - switching in and out of full-screen mode
  43.    - quitting the viewer
  44.    - generating arbitrary key and mouse events, e.g. sending ctrl-alt-del
  45.    - transferring the selection to or from the VNC server
  46.  
  47.   By default, key presses in the popup window get sent to the VNC server and
  48.   dismiss the popup.  So to get an F8 through to the VNC server simply press it
  49.   twice.
  50.  
  51. * Although still single-threaded, it behaves much like a multi-threaded client.
  52.   The main thread of the program just dispatches VNC protocol messages.  X
  53.   events are automatically processed whenever reading from the VNC connection
  54.   would block.
  55.  
  56.   So for example, over a slow link, key and mouse presses are sent to the
  57.   server even when drawing a screen update.  Previously they would only have
  58.   been sent at the end of the update.  In some cases this can save time by
  59.   skipping intermediate screen states.
  60.  
  61.  
  62. Resources
  63. ---------
  64.  
  65. You can set X resources by any of the usual means - in an app-defaults file
  66. such as .Xresources, or on the command line with the '-xrm' option,
  67. e.g. vncviewer -xrm '*passwordDialog: true'.
  68.  
  69. The file Vncviewer contains the same resource settings as the "fallback
  70. resources" embedded in the executable.  You can copy this file into
  71. /usr/lib/X11/app-defaults (or equivalent) and edit it for site-wide
  72. customisations.
  73.  
  74. The application resources are:
  75.  
  76.   shareDesktop (option -shared)
  77.  
  78.     Whether to leave other viewers connected.  Default false.
  79.  
  80.   viewOnly (option -viewonly)
  81.  
  82.     Block mouse and keyboard events.  Default false.
  83.  
  84.   fullScreen (option -fullscreen)
  85.  
  86.     Full screen mode.  Default false.
  87.  
  88.   passwordFile (option -passwd)
  89.  
  90.     File from which to get the password (as generated by the vncpasswd
  91.     program).  Default is null, i.e. to request password from the user.
  92.  
  93.   passwordDialog
  94.  
  95.     Whether to use a dialog box to get the password (true) or get it from the
  96.     tty (false).  Irrelevant if passwordFile is set.  Default false.
  97.  
  98.   encodings (option -encodings)
  99.  
  100.     A list of encodings to use in order of preference, separated by spaces.
  101.     Default is null, which actually means "copyrect hextile corre rre", or "raw
  102.     copyrect hextile corre rre" for a VNC server on the same machine.
  103.  
  104.   useBGR233 (option -bgr233)
  105.  
  106.     Always use the BGR233 (8-bit) pixel format on the wire, regardless of the
  107.     visual.  Default is false (though BGR233 is used anyway for non-TrueColor
  108.     visuals with forceOwnCmap false).
  109.  
  110.   nColours
  111.  
  112.     When using BGR233, try to allocate this many "exact" colours from the
  113.     BGR233 colour cube.  When using a shared colormap, setting this resource
  114.     lower leaves more colours for other X clients.  Irrelevant when using
  115.     truecolour.  Default is 256 (i.e. all of them).
  116.  
  117.   useSharedColours
  118.  
  119.     If the number of "exact" BGR233 colours successfully allocated is less than
  120.     256 then the rest are filled in using the "nearest" colours available.
  121.     This resource says whether to only use the "exact" BGR233 colours for this
  122.     purpose, or whether to use other clients' "shared" colours as well.
  123.     Default true (i.e. use other clients' colours).
  124.  
  125.   forceOwnCmap (option -owncmap)
  126.  
  127.     Try to use a PseudoColor visual and a private colormap - this allows the
  128.     VNC server to control the colormap.  Default false.
  129.  
  130.   forceTrueColour (option -truecolour)
  131.  
  132.     Try to use a TrueColor visual.  Default false.
  133.  
  134.   requestedDepth (option -depth)
  135.  
  136.     If forceTrueColour is true, try to use a visual of this depth.  Default 0
  137.     (i.e. any depth).
  138.  
  139.   useSharedMemory
  140.  
  141.     Whether to use the MIT shared memory extension if on the same machine as
  142.     the X server.  Default true.
  143.  
  144.   wmDecorationWidth
  145.   wmDecorationHeight
  146.  
  147.     The total width and height taken up by window manager decorations.  This is
  148.     used to calculate the maximum size of the VNC viewer window.  Default is
  149.     width 4, height 24.
  150.  
  151.   bumpScrollTime
  152.   bumpScrollPixels
  153.  
  154.     When in full screen mode and the VNC desktop is bigger than the X display,
  155.     scrolling happens whenever the mouse hits the edge of the screen.  The
  156.     maximum speed of scrolling is bumpScrollPixels pixels every bumpScrollTime
  157.     milliseconds.  The actual speed of scrolling will be slower than this, of
  158.     course, depending on how fast your machine is.  Default 20 pixels every 25
  159.     milliseconds.
  160.  
  161.   popupButtonCount
  162.  
  163.     The number of buttons in the popup window.  See below for how to customise
  164.     the buttons.
  165.  
  166.   rawDelay
  167.  
  168.     This is useful for debugging VNC servers by checking exactly which parts of
  169.     the screen are being updated.  For each update rectangle vncviewer puts up
  170.     a black rectangle for the given time in milliseconds before putting up the
  171.     pixel data.  This only highlights pixel data sent using the raw encoding.
  172.     Default 0 (i.e. don't do it).
  173.  
  174.   copyRectDelay
  175.  
  176.     Similar to rawDelay, but highlights the areas copied using the copyrect
  177.     encoding.
  178.  
  179.  
  180. How to customise the popup window
  181. ---------------------------------
  182.  
  183. Set the number of buttons with the popupButtonCount resource, e.g.:
  184.  
  185.   *popupButtonCount: 2
  186.  
  187. For each button, set the label, and override the button press translations,
  188. e.g.:
  189.  
  190.   *popup*button1.label: Send left mouse button click at 100,100
  191.   *popup*button1.translations: #override\n\
  192.     <Btn1Down>,<Btn1Up>: SendRFBEvent(ptr,100,100,1)\
  193.                          SendRFBEvent(ptr,100,100,0)
  194.  
  195.   *popup*button2.label: Send "Think thin!"
  196.   *popup*button2.translations: #override\n\
  197.     <Btn1Down>,<Btn1Up>:\
  198.       SendRFBEvent(key,T) SendRFBEvent(key,h) SendRFBEvent(key,i)\
  199.       SendRFBEvent(key,n) SendRFBEvent(key,k) SendRFBEvent(key,space)\
  200.       SendRFBEvent(key,t) SendRFBEvent(key,h) SendRFBEvent(key,i)\
  201.       SendRFBEvent(key,n) SendRFBEvent(key,exclam)
  202.  
  203.  
  204. How to customise the desktop window
  205. -----------------------------------
  206.  
  207. You can override translations on the desktop window.  For example to change the
  208. key used to bring up to popup window from F8 to Escape, and make F12 switch in
  209. and out of full screen mode:
  210.  
  211.   *desktop.translations: #override\n\
  212.     <Key>F8: SendRFBEvent()\n\
  213.     <Key>Escape: ShowPopup()\n\
  214.     <Key>F12: ToggleFullScreen()
  215.  
  216.  
  217.  
  218. Actions
  219. -------
  220.  
  221. These are the actions which you can use in translations:
  222.  
  223.   ShowPopup()
  224.   HidePopup()
  225.  
  226.     Show and hide the popup window, respectively.  
  227.  
  228.  
  229.   SendRFBEvent()
  230.  
  231.     Send an RFB event to the VNC server.  With no argument, simply sends the
  232.     RFB equivalent of the X event which caused the action.  With arguments,
  233.     generates either key or pointer events depending on the arguments:
  234.  
  235.       SendRFBEvent(keydown,<keysym>)
  236.       SendRFBEvent(keyup,<keysym>)
  237.       SendRFBEvent(key,<keysym>)    (short for keydown followed by keyup)
  238.  
  239.       SendRFBEvent(ptr,<x>,<y>,<buttonMask>)
  240.       SendRFBEvent(ptr,<buttonMask>)
  241.  
  242.     where
  243.  
  244.       <keysym> is the string representing an X keysym.  The best way to find
  245.       these is to use "xev", or look in /usr/include/X11/keysymdef.h and strip
  246.       off the "XK_".
  247.  
  248.       <x> and <y> are the position of the pointer event.  If not specified, use
  249.       the position of the X event which caused the action.
  250.  
  251.       <buttonMask> is a bit mask representing buttons 1 to 8 with bits 0 to
  252.       7 respectively, 0 meaning up, 1 meaning down (pressed).  So 0 means no
  253.       buttons, 1 means button 1 pressed, 5 means buttons 1 & 3 pressed, etc.
  254.  
  255.  
  256.   SelectionToVNC()
  257.  
  258.     Send the local X selection or cut buffer to the VNC server.  This is
  259.     usually invoked when the mouse enters the viewer window.  With no argument
  260.     or an argument "new", this is only done if this is a "new" selection,
  261.     i.e. it hasn't already been sent.  With an argument "always", it is sent
  262.     each time.
  263.  
  264.  
  265.   SelectionFromVNC()
  266.  
  267.     Set the local X selection and cut buffer to the current value of the VNC
  268.     server "cut text".  This is usually invoked when the mouse leaves the
  269.     viewer window.  With no argument or an argument "new", this is only done if
  270.     there has been new "cut text" since the last time it was called.  With an
  271.     argument "always", it is set each time.
  272.  
  273.  
  274.   Quit()
  275.  
  276.     Quit the VNC viewer.
  277.  
  278.  
  279.   Pause()
  280.  
  281.     Pause for a given number of milliseconds (100 by default).  This is
  282.     sometimes useful to space out events generated by SendRFBEvent.
  283.  
  284.  
  285.   ToggleFullScreen()
  286.  
  287.     Toggle in and out of full screen mode.
  288.  
  289.  
  290.   SetFullScreenState()
  291.  
  292.     Sets the "state" resource of a toggle widget to reflect whether we're in
  293.     full screen mode.
  294.  
  295.  
  296.   ServerDialogDone()
  297.   PasswordDialogDone()
  298.  
  299.     Used to tell the dialog boxes that entry has finished.  Usually invoked by
  300.     the return key.
  301.  
  302.  
  303. Widget hierarchy
  304. ----------------
  305.  
  306. Main window:
  307.  
  308.   Vncviewer  vncviewer
  309.     Form       form
  310.       Viewport   viewport
  311.         Core       desktop
  312.  
  313.  
  314. Server dialog box:
  315.  
  316.     TransientShell  serverDialog
  317.       Dialog          dialog
  318.  
  319.  
  320. Password dialog box:
  321.  
  322.     TransientShell  passwordDialog
  323.       Dialog          dialog
  324.  
  325.  
  326. Popup window:
  327.  
  328.     TransientShell   popup
  329.       Form             buttonForm
  330.         Command/Toggle   button1
  331.                .            .
  332.                .            .
  333.         Command/Toggle   buttonN
  334.